Python FastAPI Middleware: Sveobuhvatni vodič za obradu zahtjeva i odgovora

U svijetu modernog razvoja weba, izvedba, sigurnost i održavanje su najvažniji. Pythonov FastAPI okvir brzo je stekao popularnost zbog svoje nevjerojatne brzine i značajki prilagođenih programerima. Jedna od njegovih najmoćnijih, ali ponekad nerazumljivih značajki je middleware. Middleware djeluje kao ključna karika u lancu obrade zahtjeva i odgovora, omogućujući programerima da izvršavaju kod, mijenjaju podatke i provode pravila prije nego što zahtjev stigne do odredišta ili prije nego što se odgovor pošalje natrag klijentu.

Ovaj sveobuhvatni vodič namijenjen je globalnoj publici programera, od onih koji tek počinju s FastAPI-jem do iskusnih profesionalaca koji žele produbiti svoje razumijevanje. Istražit ćemo osnovne koncepte middlewarea, pokazati kako izgraditi prilagođena rješenja i proći kroz praktične primjere iz stvarnog svijeta. Do kraja, bit ćete opremljeni da iskoristite middleware za izgradnju robusnijih, sigurnijih i učinkovitijih API-ja.

Što je Middleware u kontekstu web okvira?

Prije nego što uđemo u kod, bitno je razumjeti koncept. Zamislite ciklus zahtjev-odgovor vaše aplikacije kao cjevovod ili montažnu liniju. Kada klijent pošalje zahtjev vašem API-ju, on ne pogađa odmah logiku vaše krajnje točke. Umjesto toga, prolazi kroz niz koraka obrade. Slično, kada vaša krajnja točka generira odgovor, on putuje natrag kroz ove korake prije nego što dođe do klijenta. Komponente middlewarea su upravo ti koraci u cjevovodu.

Popularna analogija je model luka. Jezgra luka je poslovna logika vaše aplikacije (krajnja točka). Svaki sloj luka koji okružuje jezgru je dio middlewarea. Zahtjev se mora probiti kroz svaki vanjski sloj da bi došao do jezgre, a odgovor putuje natrag kroz iste slojeve. Svaki sloj može ispitati i izmijeniti zahtjev na putu unutra i odgovor na putu van.

U suštini, middleware je funkcija ili klasa koja ima pristup objektu zahtjeva, objektu odgovora i sljedećem middlewareu u ciklusu zahtjev-odgovor aplikacije. Njegove primarne svrhe uključuju:

• Izvršavanje koda: Izvršavanje radnji za svaki dolazni zahtjev, kao što su zapisivanje ili praćenje performansi.
• Izmjena zahtjeva i odgovora: Dodavanje zaglavlja, komprimiranje tijela odgovora ili transformacija formata podataka.
• Prekidanje ciklusa: Završetak ciklusa zahtjev-odgovor rano. Na primjer, autentifikacijski middleware može blokirati neautentificirani zahtjev prije nego što uopće dosegne predviđenu krajnju točku.
• Upravljanje globalnim problemima: Rješavanje problema koji se tiču ​​više područja, kao što su rukovanje greškama, CORS (dijeljenje resursa između različitih izvora) i upravljanje sesijama na centraliziranom mjestu.

FastAPI je izgrađen na vrhu Starlette alata, koji pruža robusnu implementaciju ASGI (Asynchronous Server Gateway Interface) standarda. Middleware je temeljna koncepcija u ASGI-ju, što ga čini prvoklasnim građaninom u ekosustavu FastAPI.

Najjednostavniji oblik: FastAPI Middleware s dekoratorom

FastAPI nudi jednostavan način za dodavanje middlewarea pomoću @app.middleware("http") dekoratora. Ovo je savršeno za jednostavnu, samostalnu logiku koja se mora pokrenuti za svaki HTTP zahtjev.

Napravimo klasičan primjer: middleware za izračunavanje vremena obrade za svaki zahtjev i njegovo dodavanje u zaglavlja odgovora. Ovo je nevjerojatno korisno za praćenje performansi.

Primjer: Middleware za vrijeme obrade

Prvo, provjerite jeste li instalirali FastAPI i ASGI poslužitelj poput Uvicorna:

pip install fastapi uvicorn

Sada, napišimo kod u datoteci pod nazivom main.py:

import time

from fastapi import FastAPI, Request

app = FastAPI()

# Definirajte funkciju middlewarea

@app.middleware("http")

async def add_process_time_header(request: Request, call_next):

# Zabilježite vrijeme početka kada zahtjev dođe

start_time = time.time()

# Nastavite s sljedećim middlewareom ili krajnjom točkom

response = await call_next(request)

# Izračunajte vrijeme obrade

process_time = time.time() - start_time

# Dodajte prilagođeno zaglavlje u odgovor

response.headers["X-Process-Time"] = str(process_time)

return response

@app.get("/")

async def root():

# Simulirajte neki rad

time.sleep(0.5)

return {"message": "Hello, World!"}

Da biste pokrenuli ovu aplikaciju, koristite naredbu:

uvicorn main:app --reload

Sada, ako pošaljete zahtjev na http://127.0.0.1:8000 pomoću alata kao što je cURL ili API klijenta kao što je Postman, vidjet ćete novo zaglavlje u odgovoru, X-Process-Time, s vrijednošću od otprilike 0,5 sekundi.

Rastavljanje koda:

• @app.middleware("http"): Ovaj dekorator registrira našu funkciju kao dio HTTP middlewarea.
• async def add_process_time_header(request: Request, call_next):: Funkcija middlewarea mora biti asinkrona. Prima dolazni objekt Request i posebnu funkciju, call_next.
• response = await call_next(request): Ovo je najkritičnija linija. call_next prosljeđuje zahtjev na sljedeći korak u cjevovodu (ili drugi middleware ili stvarnu operaciju staze). Morate `await` ovaj poziv. Rezultat je objekt Response generiran od strane krajnje točke.
• response.headers[...] = ...: Nakon što je odgovor primljen s krajnje točke, možemo ga izmijeniti, u ovom slučaju, dodavanjem prilagođenog zaglavlja.
• return response: Konačno, izmijenjeni odgovor se vraća kako bi se poslao klijentu.

Izrada vlastitog prilagođenog middlewarea s klasama

Iako je pristup s dekoratorom jednostavan, može postati ograničavajući za složenije scenarije, posebno kada vaš middleware zahtijeva konfiguraciju ili treba upravljati nekim internim stanjem. Za ove slučajeve, FastAPI (putem Starlettea) podržava middleware temeljen na klasama pomoću BaseHTTPMiddleware.

Pristup temeljen na klasama nudi bolju strukturu, dopušta ubrizgavanje ovisnosti u svom konstruktoru i općenito je održiviji za složenu logiku. Osnovna logika nalazi se u asinkronoj dispatch metodi.

Primjer: Middleware za provjeru autentičnosti API ključa temeljen na klasi

Izgradimo praktičniji middleware koji osigurava naš API. Provjerit će određeno zaglavlje, X-API-Key, a ako ključ nije prisutan ili je nevažeći, odmah će vratiti odgovor s greškom 403 Forbidden. Ovo je primjer "kratkog spoja" zahtjeva.

U main.py:

from fastapi import FastAPI, Request

from fastapi.responses import JSONResponse

from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint

from starlette.responses import Response

# Popis valjanih API ključeva. U stvarnoj aplikaciji, to bi došlo iz baze podataka ili sigurnog trezora.

VALID_API_KEYS = ["my-super-secret-key", "another-valid-key"]

class APIKeyMiddleware(BaseHTTPMiddleware):

async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:

api_key = request.headers.get("X-API-Key")

if api_key not in VALID_API_KEYS:

# Kratko spojite zahtjev i vratite odgovor s greškom

return JSONResponse(

status_code=403,

content={"detail": "Zabranjeno: Nevažeći ili nedostajući API ključ"}

)

# Ako je ključ valjan, nastavite sa zahtjevom

response = await call_next(request)

return response

app = FastAPI()

# Dodajte middleware aplikaciji

app.add_middleware(APIKeyMiddleware)

@app.get("/")

async def root():

return {"message": "Dobrodošli u sigurnu zonu!"}

Sada, kada pokrenete ovu aplikaciju:

• Zahtjev bez zaglavlja X-API-Key (ili s pogrešnom vrijednošću) primit će statusni kod 403 i JSON poruku o pogrešci.
• Zahtjev s zaglavljem X-API-Key: my-super-secret-key uspjet će i primit će odgovor 200 OK.

Ovaj uzorak je izuzetno moćan. Kod krajnje točke na / ne treba znati ništa o provjeri valjanosti API ključa; ta se briga potpuno odvaja u sloj middlewarea.

Uobičajeni i moćni slučajevi upotrebe middlewarea

Middleware je savršen alat za rješavanje problema koji se tiču ​​više područja. Istražimo neke od najčešćih i najutjecajnijih slučajeva upotrebe.

1. Centralizirano zapisivanje

Sveobuhvatno zapisivanje je neosporno za produkcijske aplikacije. Middleware vam omogućuje stvaranje jedne točke na kojoj bilježite kritične informacije o svakom zahtjevu i odgovoru koji mu odgovara.

Primjer middlewarea za zapisivanje:

import logging

from fastapi import FastAPI, Request

import time

logging.basicConfig(level=logging.INFO)

logger = logging.getLogger(__name__)

app = FastAPI()

@app.middleware("http")

async def logging_middleware(request: Request, call_next):

start_time = time.time()

# Zapisivanje detalja zahtjeva

logger.info(f"Dolazni zahtjev: {request.method} {request.url.path}")

response = await call_next(request)

process_time = time.time() - start_time

# Zapisivanje detalja odgovora

logger.info(f"Status odgovora: {response.status_code} | Vrijeme obrade: {process_time:.4f}s")

return response

Ovaj middleware zapisuje metodu i put zahtjeva na putu prema unutra te statusni kod odgovora i ukupno vrijeme obrade na putu prema van. To pruža neprocjenjivu vidljivost u promet vaše aplikacije.

2. Globalno rukovanje greškama

Prema zadanim postavkama, neobrađena iznimka u vašem kodu rezultirat će greškom 500 Internal Server Error, potencijalno izlažući tragove stoga i detalje implementacije klijentu. Globalni middleware za rukovanje greškama može uhvatiti sve iznimke, zapisati ih za internu reviziju i vratiti standardizirani, korisnički prilagođen odgovor s greškom.

Primjer middlewarea za rukovanje greškama:

from fastapi import FastAPI, Request

from fastapi.responses import JSONResponse

import logging

logger = logging.getLogger(__name__)

app = FastAPI()

@app.middleware("http")

async def error_handling_middleware(request: Request, call_next):

try:

return await call_next(request)

except Exception as e:

logger.error(f"Došlo je do neobrađene pogreške: {e}", exc_info=True)

return JSONResponse(

status_code=500,

content={"detail": "Došlo je do interne pogreške poslužitelja. Pokušajte ponovo kasnije."}

)

@app.get("/error")

async def cause_error():

return 1 / 0 # Ovo će pokrenuti ZeroDivisionError

S ovim middlewareom na mjestu, zahtjev za /error više neće srušiti poslužitelj niti otkriti trag stoga. Umjesto toga, graciozno će vratiti statusni kod 500 s čistim JSON tijelom, dok se puna greška bilježi na strani poslužitelja kako bi je programeri mogli istražiti.

3. CORS (Cross-Origin Resource Sharing)

Ako se vaša front-end aplikacija poslužuje s druge domene, protokola ili porta od vaše FastAPI pozadine, preglednici će blokirati zahtjeve zbog pravila iste domene. CORS je mehanizam za ublažavanje ovog pravila. FastAPI pruža namjenski, visoko konfigurabilni CORSMiddleware u tu svrhu.

Primjer CORS konfiguracije:

from fastapi import FastAPI

from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Definirajte popis dopuštenih izvora. Koristite "*" za javne API-je, ali budite specifični za bolju sigurnost.

origins = [

"http://localhost:3000",

"https://my-production-frontend.com",

]

app.add_middleware(

CORSMiddleware,

allow_origins=origins,

allow_credentials=True, # Dopusti da se kolačići uključe u zahtjeve s različitih izvora

allow_methods=["*"], # Dopusti sve standardne HTTP metode

allow_headers=["*"], # Dopusti sva zaglavlja

)

Ovo je jedan od prvih dijelova middlewarea koje ćete vjerojatno dodati bilo kojem projektu s odvojenim front-endom, što olakšava upravljanje politikama različitih izvora s jedne, centralne lokacije.

4. GZip kompresija

Komprimiranje HTTP odgovora može značajno smanjiti njihovu veličinu, što dovodi do bržeg vremena učitavanja za klijente i nižih troškova propusnosti. FastAPI uključuje GZipMiddleware za automatsko rješavanje toga.

Primjer GZip middlewarea:

from fastapi import FastAPI

from fastapi.middleware.gzip import GZipMiddleware

app = FastAPI()

# Dodajte GZip middleware. Možete postaviti minimalnu veličinu za kompresiju.

app.add_middleware(GZipMiddleware, minimum_size=1000)

@app.get("/")

async def root():

# Ovaj odgovor je mali i neće biti komprimiran.

return {"message": "Hello World"}

@app.get("/large-data")

async def large_data():

# Ovaj veliki odgovor automatski će biti komprimiran pomoću middlewarea.

return {"data": "a_very_long_string..." * 1000}

S ovim middlewareom, svaki odgovor veći od 1000 bajtova bit će komprimiran ako klijent naznači da prihvaća GZip kodiranje (što praktički svi moderni preglednici i klijenti rade).

Napredni koncepti i najbolje prakse

Kako postajete vještiji u middlewareu, važno je razumjeti neke nijanse i najbolje prakse za pisanje čistog, učinkovitog i predvidljivog koda.

1. Redoslijed middlewarea je važan!

Ovo je najkritičnije pravilo koje treba zapamtiti. Middleware se obrađuje redoslijedom kojim se dodaje u aplikaciju. Prvi dodani middleware je najudaljeniji sloj "luka".

Razmotrite ovo postavljanje:

app.add_middleware(ErrorHandlingMiddleware) # Najudaljeniji

app.add_middleware(LoggingMiddleware)

app.add_middleware(AuthenticationMiddleware) # Najdublji

Tok zahtjeva bi bio:

1. ErrorHandlingMiddleware prima zahtjev. Omotava svoj `call_next` u blok `try...except`.
2. Poziva `next`, prosljeđujući zahtjev na `LoggingMiddleware`.
3. LoggingMiddleware prima zahtjev, zapisuje ga i poziva `next`.
4. AuthenticationMiddleware prima zahtjev, provjerava vjerodajnice i poziva `next`.
5. Zahtjev konačno stiže do krajnje točke.
6. Krajnja točka vraća odgovor.
7. AuthenticationMiddleware prima odgovor i prosljeđuje ga.
8. LoggingMiddleware prima odgovor, zapisuje ga i prosljeđuje ga.
9. ErrorHandlingMiddleware prima konačni odgovor i vraća ga klijentu.

Ovaj je redoslijed logičan: rukovatelj pogreškama je izvana tako da može uhvatiti pogreške iz bilo kojeg sljedećeg sloja, uključujući i ostale middlewaree. Sloj autentifikacije je duboko unutra, pa se ne trudimo zapisivati ​​ili obrađivati ​​zahtjeve koji će ionako biti odbijeni.

2. Prosljeđivanje podataka s `request.state`

Ponekad middleware mora proslijediti informacije krajnjoj točki. Na primjer, autentifikacijski middleware može dekodirati JWT i izdvojiti korisnički ID. Kako može učiniti ovaj korisnički ID dostupnim funkciji operacije staze?

Pogrešan način je izravna izmjena objekta zahtjeva. Ispravan način je korištenje objekta request.state. To je jednostavan, prazan objekt predviđen za upravo tu svrhu.

Primjer: Prosljeđivanje korisničkih podataka s middlewarea

# U metodi dispatch vašeg middlewarea za autentifikaciju:

# ... nakon provjere tokena i dekodiranja korisnika ...

user_data = {"id": 123, "username": "global_dev"}

request.state.user = user_data

response = await call_next(request)

# U vašoj krajnjoj točki:

@app.get("/profile")

async def get_user_profile(request: Request):

current_user = request.state.user

return {"profile_for": current_user}

Ovo održava logiku čistom i izbjegava zagađivanje prostora imena objekta `Request`.

3. Razmatranja izvedbe

Iako je middleware moćan, svaki sloj dodaje malu količinu režije. Za aplikacije visokih performansi, imajte na umu ove točke:

• Neka bude vitko: Logika middlewarea trebala bi biti što brža i učinkovitija.
• Budi asinkroni: Ako vaš middleware mora izvršiti I/O operacije (poput provjere baze podataka), osigurajte da je potpuno `async` kako biste izbjegli blokiranje petlje događaja poslužitelja.
• Koristite s svrhom: Nemojte dodavati middleware koji vam nije potreban. Svaki dodaje dubinu stog poziva i vrijeme obrade.

4. Testiranje vašeg middlewarea

Middleware je kritični dio logike vaše aplikacije i trebao bi se temeljito testirati. FastAPI-jev `TestClient` to olakšava. Možete napisati testove koji šalju zahtjeve sa i bez potrebnih uvjeta (npr. sa i bez valjanog API ključa) i potvrditi da se middleware ponaša kako se očekuje.

Primjer testa za APIKeyMiddleware:

from fastapi.testclient import TestClient

from .main import app # Uvezite svoju FastAPI aplikaciju

client = TestClient(app)

def test_request_without_api_key_is_forbidden():

response = client.get("/")

assert response.status_code == 403

assert response.json() == {"detail": "Forbidden: Invalid or missing API Key"}

def test_request_with_valid_api_key_is_successful():

headers = {"X-API-Key": "my-super-secret-key"}

response = client.get("/", headers=headers)

assert response.status_code == 200

assert response.json() == {"message": "Welcome to the secure zone!"}

Zaključak

FastAPI middleware je temeljni i moćan alat za svakog programera koji gradi moderne web API-je. Pruža elegantan i višekratan način za rješavanje problema koji se tiču ​​više područja, odvajajući ih od vaše osnovne poslovne logike. Presretanjem i obradom svakog zahtjeva i odgovora, middleware vam omogućuje implementaciju robusnog zapisivanja, centraliziranog rukovanja greškama, strogih sigurnosnih politika i poboljšanja performansi poput kompresije.

Od jednostavnog @app.middleware("http") dekoratora do sofisticiranih rješenja temeljenih na klasama, imate fleksibilnost da odaberete pravi pristup za svoje potrebe. Razumijevanjem osnovnih koncepata, uobičajenih slučajeva upotrebe i najboljih praksi poput redoslijeda middlewarea i upravljanja stanjem, možete izgraditi čišće, sigurnije i visoko održive FastAPI aplikacije.

Sada ste na redu. Počnite integrirati prilagođeni middleware u svoj sljedeći FastAPI projekt i otključajte novu razinu kontrole i elegancije u dizajnu svog API-ja. Mogućnosti su ogromne, a savladavanje ove značajke nedvojbeno će vas učiniti učinkovitijim i efikasnijim programerom.